<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<title></title>
<meta name="Generator" content="Cocoa HTML Writer">
<meta name="CocoaVersion" content="824.42">
<style type="text/css">
p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #b31a06}
p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #942413}
span.s1 {color: #002db1}
span.s2 {color: #466a21}
span.s3 {color: #0019bc}
span.s4 {color: #000000}
span.s5 {color: #606060}
span.s6 {color: #0014bd}
span.s7 {color: #20710d}
span.s8 {color: #942413}
span.s9 {color: #3a6d1a}
span.s10 {text-decoration: underline}
span.Apple-tab-span {white-space:pre}
</style>
</head>
<body>
<p class="p1"><b>OnsetsDS<span class="Apple-converted-space">    </span>Onset detector</b></p>
<p class="p2"><br></p>
<p class="p3"><b><span class="Apple-tab-span">	</span></b><span class="s1"><b>OnsetsDS</b></span><b>.kr(in, fftbuf, trackbuf, thresh=0.5, type=</b><span class="s2"><b>\power</b></span><b>)</b></p>
<p class="p2"><br></p>
<p class="p3">An onset detector for musical audio signals - i.e. detects the beginning of notes/drumbeats/etc. Outputs a control-rate trigger signal which is 1 when an onset is detected, and 0 otherwise.</p>
<p class="p2"><br></p>
<p class="p3">The onset detection should work well for a general range of monophonic and polyphonic audio signals, but is <i>not</i> targeted at sounds like solo voice, flute, or choir, which have their own specific qualities and tend to be difficult for general-purpose onset detectors. The onset detection is purely based on signal analysis and does not make use of any "top-down" inferences such as tempo.</p>
<p class="p2"><br></p>
<p class="p3">The input to the onset detector should be single-channel. As with most UGens, it will automatically be expanded out to cater for multiple channels, but they'll be completely separate detectors. Typically you'll only want a single output even for stereo input, so remember to mix down signals before feeding them in, if needed.</p>
<p class="p2"><br></p>
<p class="p2"><br></p>
<p class="p3"><b>Example</b></p>
<p class="p2"><br></p>
<p class="p4">(</p>
<p class="p4">s.boot.doWhenBooted({</p>
<p class="p5">// Prepare the buffers</p>
<p class="p4">b = <span class="s3">Buffer</span>.alloc(s, 512);</p>
<p class="p4">c = <span class="s3">Buffer</span>.alloc(s, 512);</p>
<p class="p5"><span class="s4">d = </span><span class="s3">Buffer</span><span class="s4">.read(s, </span><span class="s5">"sounds/a11wlk01.wav"</span><span class="s4">); </span>//<span class="Apple-converted-space">  </span>Feel free to load a more interesting clip!</p>
<p class="p4">});</p>
<p class="p4">)</p>
<p class="p6"><br></p>
<p class="p4">(</p>
<p class="p4">x = {</p>
<p class="p4"><span class="Apple-tab-span">	</span><span class="s3">var</span> sig, onsets, pips;</p>
<p class="p4"><span class="Apple-tab-span">	</span>sig = <span class="s3">PlayBuf</span>.ar(1, d.bufnum, <span class="s3">BufRateScale</span>.kr(d.bufnum), loop: 1);</p>
<p class="p6"><span class="Apple-tab-span">	</span></p>
<p class="p5"><span class="s4"><span class="Apple-tab-span">	</span></span>// OnsetsDS - move the mouse left/right to change the threshold:</p>
<p class="p4"><span class="Apple-tab-span">	</span>onsets = <span class="s3">OnsetsDS</span>.kr(sig, b.bufnum, c.bufnum, <span class="s6">MouseX</span>.kr(0,1), <span class="s7">\complex</span>);</p>
<p class="p6"><span class="Apple-tab-span">	</span></p>
<p class="p4"><span class="Apple-tab-span">	</span>pips = <span class="s3">SinOsc</span>.ar(880, 0, <span class="s3">EnvGen</span>.kr(<span class="s3">Env</span>.perc(0.001, 0.1, 0.2), onsets));</p>
<p class="p4"><span class="Apple-tab-span">	</span><span class="s3">Out</span>.ar(0, ((sig * 0.1) + pips).dup);</p>
<p class="p4">}.play;</p>
<p class="p4">)</p>
<p class="p6"><br></p>
<p class="p7"><span class="s4">x.free; </span>// Free the synth</p>
<p class="p4">[b,c,d].do(<span class="s1">_</span>.free); <span class="s8">// Free the buffers</span></p>
<p class="p2"><br></p>
<p class="p2"><br></p>
<p class="p3">The <b>thresh</b> value is a detection threshold, typical values for which are expected to range between 0 and 1, although values outside that range are allowed and may in rare cases be more appropriate for you. The default of 0.5 should give a generally decent balance.</p>
<p class="p2"><br></p>
<p class="p3">The onset detector requires two buffers of the same size (<b>fftbuf</b> and <b>trackbuf</b>) to be passed in. It uses them internally for its FFT-based processing. Recommended size for these buffers is 512, although you may like to try other sizes (you may need to fiddle with the threshold settings etc).</p>
<p class="p2"><br></p>
<p class="p3">The <b>type</b> argument chooses which <i>onset detection function</i> is used. The following choices are available:</p>
<p class="p2"><br></p>
<p class="p3"><span class="Apple-converted-space"> </span>* <span class="s2">\power</span><span class="Apple-converted-space">    </span>- the default, this is generally good and also very efficient</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <span class="s2">\complex</span><span class="Apple-converted-space">  </span>- performs very well indeed, but less efficient</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <span class="s2">\rcomplex</span> - almost as good as <span class="s2">\complex</span>, and slightly more efficient</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <span class="s2">\wphase</span> <span class="Apple-converted-space">  </span>- generally very good, medium efficiency</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <span class="s2">\mkl</span><span class="Apple-converted-space">      </span>- generally very good, medium efficiency</p>
<p class="p2"><br></p>
<p class="p3">Which of these should you choose? The differences aren't large, so I'd recommend you stick with the default unless you find specific problems with it. Then try the <span class="s9">\rcomplex</span> if you want to use more CPU for a slightly better performance. The <span class="s9">\mkl</span> type is a bit different from the others so maybe try that too. They all have slightly different characteristics though, and in my tests perform at a very similar quality level.</p>
<p class="p2"><br></p>
<p class="p3"><b><i>Note:</i></b> the <b>type</b> argument is treated specially, and only evaluated at the moment the SynthDef is <i>compiled</i>. You can't change the value after that (not even on Synth instantiation).</p>
<p class="p2"><br></p>
<p class="p3">For more details of all the processes involved, the different <i>onset detection functions</i>, and their evaluation, see</p>
<p class="p2"><br></p>
<p class="p3"><span class="Apple-tab-span">	</span>Stowell, D. and Plumbley, M. (2007) Adaptive whitening for improved real-time onset detection. To appear in <i>Proceedings of the 2007 International Computer Music Conference.</i></p>
<p class="p2"><br></p>
<p class="p3"><b><i>Note:</i></b> OnsetsDS is a "pseudo-UGen" built on top of other UGen's in Dan's MCLD UGen library, so it should not be installed "alone" on a system - it won't work without the rest of the library!</p>
<p class="p2"><br></p>
<p class="p2"><br></p>
<p class="p3">-----------</p>
<p class="p2"><br></p>
<p class="p3"><b>ADVANCED FEATURES</b></p>
<p class="p2"><br></p>
<p class="p3">Further options are available, which you are welcome to fiddle with if you want.</p>
<p class="p2"><br></p>
<p class="p3">Perhaps the most significant is <b>extchain</b> - if you set this to <i>true</i> then the onset detector expects "in" to be an FFT chain, not an audio-rate signal. This means that if you're already performing FFT on the signal you can feed the FFT chain into the onset detector, rather than having it perform a separate FFT.</p>
<p class="p2"><br></p>
<p class="p3">The other parameters are numbers that modulate the behaviour of the onset detector:</p>
<p class="p2"><br></p>
<p class="p3"><span class="Apple-converted-space"> </span>* <b>relaxtime</b>, <b>floor</b> and <b>smear</b> are parameters to the PV_Whiten UGen which is used internally. See [<span class="s10">PV_Whiten</span>] for details. (Note: in <span class="s2">\mkl</span> mode these are not used.) In particular, you may wish to push the default <b>floor</b> parameter down from its default of 0.1. For some classical music with wide dynamic variations, I found it helpful to go down as far as 0.000001.</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <b>mingap</b> specifies a minimum gap (in seconds) between onset detections, to prevent too many doubled detections.</p>
<p class="p3"><span class="Apple-converted-space"> </span>* <b>medianspan</b> specifies the size (in FFT frames) of the median window used for smoothing the detection function before triggering.</p>
<p class="p2"><br></p>
</body>
</html>
